home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / glibmm-2.4 / glibmm / convert.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-04-20  |  10.6 KB  |  300 lines
  1. // -*- c++ -*-
  2. // Generated by gtkmmproc -- DO NOT MODIFY!
  3. #ifndef _GLIBMM_CONVERT_H
  4. #define _GLIBMM_CONVERT_H
  5.  
  6.  
  7. /* $Id: convert.hg,v 1.2 2005/01/09 18:04:53 murrayc Exp $ */
  8.  
  9. /* Copyright (C) 2002 The gtkmm Development Team
  10.  *
  11.  * This library is free software; you can redistribute it and/or
  12.  * modify it under the terms of the GNU Library General Public
  13.  * License as published by the Free Software Foundation; either
  14.  * version 2 of the License, or (at your option) any later version.
  15.  *
  16.  * This library is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19.  * Library General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU Library General Public
  22.  * License along with this library; if not, write to the Free
  23.  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24.  */
  25.  
  26.  
  27. #include <glib/gtypes.h> /* for gsize */
  28.  
  29. #include <glibmm/error.h>
  30. #include <glibmm/ustring.h>
  31.  
  32. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  33. extern "C" { typedef struct _GIConv* GIConv; }
  34. #endif
  35.  
  36.  
  37. namespace Glib
  38. {
  39.  
  40. /** @defgroup CharsetConv Character Set Conversion
  41.  * Utility functions for converting strings between different character sets.
  42.  * @{
  43.  */
  44.  
  45. /** Exception class for charset conversion errors.
  46.  * Glib::convert() and friends throw a ConvertError exception if the charset
  47.  * conversion failed for some reason.  When writing non-trivial applications
  48.  * you should always catch those errors, and then try to recover, or tell the
  49.  * user the input was invalid.
  50.  */
  51. class ConvertError : public Glib::Error
  52. {
  53. public:
  54.   enum Code
  55.   {
  56.     NO_CONVERSION,
  57.     ILLEGAL_SEQUENCE,
  58.     FAILED,
  59.     PARTIAL_INPUT,
  60.     BAD_URI,
  61.     NOT_ABSOLUTE_PATH
  62.   };
  63.  
  64.   ConvertError(Code error_code, const Glib::ustring& error_message);
  65.   explicit ConvertError(GError* gobject);
  66.   Code code() const;
  67.  
  68. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  69. private:
  70.   static void throw_func(GError* gobject);
  71.   friend void wrap_init(); // uses throw_func()
  72. #endif
  73. };
  74.  
  75.  
  76. /** Thin %iconv() wrapper.
  77.  * glibmm provides Glib::convert() and Glib::locale_to_utf8() which
  78.  * are likely more convenient than the raw iconv wrappers.  However,
  79.  * creating an IConv object once and using the convert() method could
  80.  * be useful when converting multiple times between the same charsets.
  81.  */
  82. class IConv
  83. {
  84. public:
  85.   /** Open new conversion descriptor.
  86.    * @param to_codeset Destination codeset.
  87.    * @param from_codeset %Source codeset.
  88.    * @throw Glib::ConvertError
  89.    */
  90.   IConv(const std::string& to_codeset, const std::string& from_codeset);
  91.  
  92.   explicit IConv(GIConv gobject);
  93.  
  94.   /** Close conversion descriptor.
  95.    */
  96.   ~IConv();
  97.  
  98.   /** Same as the standard UNIX routine %iconv(), but may be implemented
  99.    * via libiconv on UNIX flavors that lack a native implementation.  glibmm
  100.    * provides Glib::convert() and Glib::locale_to_utf8() which are likely
  101.    * more convenient than the raw iconv wrappers.
  102.    * @param inbuf Bytes to convert.
  103.    * @param inbytes_left In/out parameter, bytes remaining to convert in @a inbuf.
  104.    * @param outbuf Converted output bytes.
  105.    * @param outbytes_left In/out parameter, bytes available to fill in @a outbuf.
  106.    * @return Count of non-reversible conversions, or <tt>static_cast<size_t>(-1)</tt> on error.
  107.    */
  108.   size_t iconv(char** inbuf, gsize* inbytes_left, char** outbuf, gsize* outbytes_left);
  109.  
  110.   /** Reset conversion descriptor to initial state.
  111.    * Same as <tt>iconv(0, 0, 0, 0)</tt>, but implemented slightly differently
  112.    * in order to work on Sun Solaris <= 7.  It's also more obvious so you're
  113.    * encouraged to use it.
  114.    */
  115.   void reset();
  116.  
  117.   /** Convert from one encoding to another.
  118.    * @param str The string to convert.
  119.    * @return The converted string.
  120.    * @throw Glib::ConvertError
  121.    */
  122.   std::string convert(const std::string& str);
  123.  
  124.   GIConv gobj() { return gobject_; }
  125.  
  126. private:
  127.   GIConv gobject_;
  128.  
  129.   // noncopyable
  130.   IConv(const IConv&);
  131.   IConv& operator=(const IConv&);
  132. };
  133.  
  134.  
  135. /** Get the charset used by the current locale.
  136.  * @return Whether the current locale uses the UTF-8 charset.
  137.  */
  138. bool get_charset();
  139.  
  140. /** Get the charset used by the current locale.
  141.  * @param charset Will be filled with the charset's name.
  142.  * @return Whether the current locale uses the UTF-8 charset.
  143.  */
  144. bool get_charset(std::string& charset);
  145.  
  146. /** Convert from one encoding to another.
  147.  * @param str The string to convert.
  148.  * @param to_codeset Name of the target charset.
  149.  * @param from_codeset Name of the source charset.
  150.  * @return The converted string.
  151.  * @throw Glib::ConvertError
  152.  */
  153. std::string convert(const std::string& str,
  154.                     const std::string& to_codeset,
  155.                     const std::string& from_codeset);
  156.  
  157. /** Converts a string from one character set to another, possibly including
  158.  * fallback sequences for characters not representable in the output.
  159.  * Characters not in the target encoding will be represented as Unicode
  160.  * escapes <tt>\\x{XXXX}</tt> or <tt>\\x{XXXXXX}</tt>.
  161.  * @param str The string to convert.
  162.  * @param to_codeset Name of the target charset.
  163.  * @param from_codeset Name of the source charset.
  164.  * @return The converted string.
  165.  * @throw Glib::ConvertError
  166.  */
  167. std::string convert_with_fallback(const std::string& str,
  168.                                   const std::string& to_codeset,
  169.                                   const std::string& from_codeset);
  170.  
  171. /** Converts a string from one character set to another, possibly including
  172.  * fallback sequences for characters not representable in the output.
  173.  * @note It is not guaranteed that the specification for the fallback sequences
  174.  * in @a fallback will be honored. Some systems may do a approximate conversion
  175.  * from @a from_codeset to @a to_codeset in their iconv() functions, in which
  176.  * case Glib will simply return that approximate conversion.
  177.  *
  178.  * @param str The string to convert.
  179.  * @param to_codeset Name of the target charset.
  180.  * @param from_codeset Name of the source charset.
  181.  * @param fallback UTF-8 string to be used in place of characters which aren't
  182.  *  available in the target encoding.  All characters in the fallback string
  183.  *  @em must be available in the target encoding.
  184.  * @return The converted string.
  185.  * @throw Glib::ConvertError
  186.  */
  187. std::string convert_with_fallback(const std::string& str,
  188.                                   const std::string& to_codeset,
  189.                                   const std::string& from_codeset,
  190.                                   const Glib::ustring& fallback);
  191.  
  192. /** Convert from the current locale's encoding to UTF-8.
  193.  * Convenience wrapper around Glib::convert().
  194.  * @param opsys_string The string to convert.  Must be encoded in the charset
  195.  *  used by the operating system's current locale.
  196.  * @return The input string converted to UTF-8 encoding.
  197.  * @throw Glib::ConvertError
  198.  */
  199. Glib::ustring locale_to_utf8(const std::string& opsys_string);
  200.  
  201. /** Convert from UTF-8 to the current locale's encoding.
  202.  * Convenience wrapper around Glib::convert().
  203.  * @param utf8_string The UTF-8 string to convert.
  204.  * @return The input string converted to the charset used by the operating
  205.  *  system's current locale.
  206.  * @throw Glib::ConvertError
  207.  */
  208. std::string locale_from_utf8(const Glib::ustring& utf8_string);
  209.  
  210. /** Converts a string which is in the encoding used for filenames into
  211.  * a UTF-8 string.
  212.  * @param opsys_string A string in the encoding for filenames.
  213.  * @return The converted string.
  214.  * @throw Glib::ConvertError
  215.  */
  216. Glib::ustring filename_to_utf8(const std::string& opsys_string);
  217.  
  218. /** Converts a string from UTF-8 to the encoding used for filenames.
  219.  * @param utf8_string A UTF-8 encoded string.
  220.  * @return The converted string.
  221.  * @throw Glib::ConvertError
  222.  */
  223. std::string filename_from_utf8(const Glib::ustring& utf8_string);
  224.  
  225. /** Converts an escaped UTF-8 encoded URI to a local filename
  226.  * in the encoding used for filenames.
  227.  * @param uri A string in the encoding for filenames.
  228.  * @param hostname Location to store hostname for the URI. If there is no
  229.  *   hostname in the URI, <tt>""</tt> will be stored in this location.
  230.  * @return The resulting filename.
  231.  * @throw Glib::ConvertError
  232.  */
  233. std::string filename_from_uri(const Glib::ustring& uri, Glib::ustring& hostname);
  234.  
  235. /** Converts an escaped UTF-8 encoded URI to a local filename in the encoding
  236.  * used for filenames.
  237.  * @param uri A string in the encoding for filenames.
  238.  * @return The resulting filename.
  239.  * @throw Glib::ConvertError
  240.  */
  241. std::string filename_from_uri(const Glib::ustring& uri);
  242.  
  243. /** Converts an absolute filename to an escaped UTF-8 encoded URI.
  244.  * @param filename An absolute filename specified in the encoding used
  245.  *   for filenames by the operating system.
  246.  * @param hostname A UTF-8 encoded hostname.
  247.  * @return The resulting URI.
  248.  * @throw Glib::ConvertError
  249.  */
  250. Glib::ustring filename_to_uri(const std::string& filename, const Glib::ustring& hostname);
  251.  
  252. /** Converts an absolute filename to an escaped UTF-8 encoded URI.
  253.  * @param filename An absolute filename specified in the encoding used
  254.  *   for filenames by the operating system.
  255.  * @return The resulting URI.
  256.  * @throw Glib::ConvertError
  257.  */
  258. Glib::ustring filename_to_uri(const std::string& filename);
  259.  
  260. /** Returns the display basename for the particular filename, guaranteed
  261.  * to be valid UTF-8. The display name might not be identical to the filename,
  262.  * for instance there might be problems converting it to UTF-8, and some files
  263.  * can be translated in the display
  264.  *
  265.  * You must pass the whole absolute pathname to this function so that
  266.  * translation of well known locations can be done.
  267.  *
  268.  * This function is preferred over filename_display_name() if you know the
  269.  * whole path, as it allows translation.
  270.  *
  271.  * @param filename An absolute pathname in the GLib file name encoding.
  272.  * @result A string containing a rendition of the basename of the filename in valid UTF-8
  273.  */
  274. Glib::ustring filename_display_basename(const std::string& filename);
  275.  
  276. /** Converts a filename into a valid UTF-8 string. The 
  277.  * conversion is not necessarily reversible, so you 
  278.  * should keep the original around and use the return
  279.  * value of this function only for display purposes.
  280.  * Unlike g_filename_to_utf8(), the result is guaranteed 
  281.  * to be non-empty even if the filename actually isn't in the GLib
  282.  * file name encoding.
  283.  *
  284.  * If you know the whole pathname of the file you should use
  285.  * g_filename_display_basename(), since that allows location-based
  286.  * translation of filenames.
  287.  *
  288.  * @param filename: a pathname hopefully in the GLib file name encoding
  289.  * @result A string containing a rendition of the filename in valid UTF-8.
  290.  */
  291. Glib::ustring filename_display_name(const Glib::ustring& filename);
  292.  
  293. /** @} group CharsetConv */
  294.  
  295. } // namespace Glib
  296.  
  297.  
  298. #endif /* _GLIBMM_CONVERT_H */
  299.  
  300.